Skip to main content

Local Installation

This chapter of the documentation focuses on setting up and running HAWKI 2.0 on your local system. If you prefer to create a local Docker environment follow Local Docker Installation

Although we strongly recommend that you first test HAWKI on your local device before deploying it on the server, If you want to skip this please read the "Deployment" chapter

Pre Requirements​

HAWKI 2.0 utilizes the Laravel 11 backend framework. To run HAWKI on your local machine, it is essential to ensure that all Laravel prerequisites are installed. In particular, you will need to have PHP, Composer and Node.js (including npm) installed on your system. For comprehensive setup instructions, please refer to the laravel documentation. HAWKI also requires a database to store the messages and profile pictures. We recommend that you use a mySQL database. The use of administration tools such as phpMyAdmin can also speed up the process.

Checking Requirements Using HAWKI CLI​

You can use the HAWKI CLI to check if your system meets all requirements. Navigate to project root (if already cloned) and run:

php hawki check

This command will verify:

  • PHP version (8.1+)
  • Composer
  • Node.js and npm
  • Required PHP extensions (mbstring, xml, pdo, curl, zip, json, fileinfo, openssl)

If any dependencies are missing, the command will provide installation instructions.

Initialization​

  1. Clone the Git Repo:
git clone https://github.com/HAWK-Digital-Environments/HAWKI.git

  1. Install Dependencies

    You can install dependencies using traditional methods:

    composer install
    npm install

    Or use the HAWKI CLI for a streamlined setup:

    php hawki init

    Using php hawki init will:

    • Create .env file from .env.example
    • Set up required configuration files
    • Install Composer dependencies
    • Install npm packages
    • Create storage symlinks
    • Generate application keys and security salts

    For a complete guided setup process, use:

    php hawki init -all

    This will run the initialization and continue with the interactive setup process.

DATABASE​

1- To store chat data, hawki requires a database connection. This documentation employs MySQL, but selection depends on your usage and specific requirements. For local development you can also use "Mamp" or "Xampp" to facilitate the process.

2- Create a new, empty database, for example HAWKI_DB.

3- Update the database connection settings in the .env file with:

DB_CONNECTION= mysql
DB_HOST= 127.0.0.1 #Database host IP
DB_PORT= 3306 #Database host port
DB_DATABASE= HAWKI_DB #Database name
DB_USERNAME= root #Database username
DB_PASSWORD= root #Database password

You can also use the HAWKI CLI to configure your database settings interactively:

php hawki setup -db

This interactive command will prompt you for database connection details with sensible defaults.

4-Run database migrations and seed data by navigating to the project directory and executing:

php artisan migrate
php artisan db:seed

Alternatively, use the HAWKI CLI:

php hawki migrate

For a fresh database (which will reset all data), use:

php hawki migrate --fresh

Configuration​

Find the .env.example file in the root directory. Rename it to .env by removing the .example extension. This step is automatically handled if you used php hawki init.

For comprehensive information on .env variables, refer to the dot env section of this documentation.

You can configure your environment using the HAWKI CLI interactive setup:

php hawki setup

This command will guide you through configuring all aspects of your HAWKI installation. Alternatively, you can configure specific sections:

php hawki setup -g    # General settings
php hawki setup -auth # Authentication settings
php hawki setup -reverb # Reverb settings

Authentication

in the .env file find AUTHENTICATION_METHOD variable. Currently HAWKI supports LDAP, OpenID, and Shibboleth authentication services. A built-in Test User Athentication for internal testing purposes is also available. Since normally external authentication servers are not accessible from your local machine, set the authentication method to LDAP to use test users.

In /storage/app/ create a json file and name it test_users.json and add your desired profiles in the json file as below:

[
    {
        "username": "tester",
        "password": "123",
        "name": "TheTester",
        "email": "tester@MyUni.de",
        "employeetype": "Tester",
        "avatar_id": ""
    },
    ...
]

Create Storage Link

To allow clients to read files from the storage folder, we need to create a symbolic link for the storage. Use the following command to create the symbolic link:

php artisan storage:link

You should be able to see the storage shortcut inside the public folder.

Please note that after changing the structure of your files in the storage folder you may need to recreate the virtual link:

sudo rm -rf public/storage
php artisan storage:link

API KEYS

Navigate to config folder. There you'll find model_providers.php.example. Also rename it to model_providers.php. Open the file and update the configuration as you need. HAWKI currently supports LLM from OpenAI, GWDG, and Google. There is currently no integration for multimodal input and output on the part of HAWKI. Audio, video and image in/output are not displayed correctly when these models are addressed. We would be pleased if the community could contribute these features.

You can also use the HAWKI CLI to configure AI model providers interactively:

php hawki setup-models

This command will allow you to:

  • Activate or deactivate AI providers
  • Set API keys for each active provider
  • Configure the default model
  • Set models for system tasks (title generation, prompt improvement, etc.)

Alternatively, edit the configuration file manually:

    // The Default Model (use the id of one of model you wish)
    'defaultModel' => 'gpt-4o',

    // The model which generates the chat names.
    'titleGenerationModel' => 'gpt-4o-mini', 

    'providers' =>[
        'openai' => [
            'id' => 'openai',
            'active' => true, //set to false if you want to disable the provider
            'api_key' => ' ** YOUR SECRET API KEY ** ',
            'api_url' => 'https://api.openai.com/v1/chat/completions',
            'ping_url' => 'https://api.openai.com/v1/models',
            'models' => [
                [
                    'id' => 'gpt-4o',
                    'label' => 'OpenAI GPT 4o',
                    'streamable' => true,
                ],
                ...  
            ]
        ],
        ...
    ]

Start Server​

  1. To start the server, you can use either:

Traditional command:

php artisan serve

Or HAWKI CLI:

php hawki run -dev

The HAWKI CLI run -dev command starts:

  • PHP development server
  • npm development server with hot-reloading
  • Reverb websocket server (if configured)
  • Queue workers for various tasks

Of course if you are using tools like Xammp or Mamp (on windows) to run apache, an nginx server, or any other methods you don't need to run these commands. However, running artisan serve creates a user friendly terminal which helps the debug process.

  1. If using traditional commands, start the node server separately:
npm run dev

You should be able to open and use HAWKI on your localhost at this stage.

http://127.0.0.1:8000/
  1. To stop all running processes when using HAWKI CLI:
php hawki stop

This command finds and terminates:

  • PHP Artisan processes
  • Node.js/npm processes
  • Queue workers
  • Reverb server

Important: You can also use localhost:8000 to open the web page in your browser. However, some of the communication is resticted by the address defined in the .env file. If you wish to change this, update the APP_URL variable in .env.

Broadcasting & Workers​

HAWKI uses Laravel Reverb for real-time communication between client and server.

In order to establish a connection to Reverb, a set of Reverb "application" credentials must be exchanged between the client and server. These credentials are configured on the server and are used to verify the request from the client. You may define these credentials using the following environment variables:

REVERB_APP_ID=my-app-id // replace with 
REVERB_APP_KEY=my-app-key
REVERB_APP_SECRET=my-app-secret

READ THE ORIGINAL DOCUMENTAITON FOR MORE DETAIL

For local testing leave the rest of the Reverb variables as is:

REVERB_HOST=127.0.0.1
REVERB_PORT=8080
REVERB_SCHEME=http

Start Reverb using:

php artisan reverb:start

In the terminal you should see:

Starting server on 0.0.0.0:8080 (127.0.0.1).

With php artisan reverb:start, clients can connect to Reverb-created group chat channels.

Using HAWKI CLI, Reverb is automatically started with the development environment:

php hawki run -dev

To clear all Laravel caches (which may be necessary after configuration changes):

php hawki clear-cache

Workers

Before a message is broadcasted it must be queued and dispatched by laravel workers.

To start workers run the following commands in separate terminals:

php artisan queue:work
php artisan queue:work --queue=message_broadcast

or simply use one of these commands:

bash run_dev.sh start
php hawki run -dev

The HAWKI CLI automatically manages all required workers when using the run -dev command.